home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1991 …esperately Seeking Seven / Desperately Seeking Seven.2mg / Dev.CD.8 / Essentials / Tools / DTS.Samples / SC20DTSToolLib / FMD.usage < prev    next >
Encoding:
Text File  |  1990-05-25  |  13.6 KB  |  245 lines  |  [04] ASCII Text (0x0000)
  1. *******************************************************************************
  2. *
  3. * fakeModalDialog and other supporting access routines and such.
  4. * Version 3.0
  5. *
  6. * Copyright (c)
  7. * Apple Computer, Inc.  1989-1990
  8. * All Rights Reserved.
  9. *
  10. * Written by Eric Soldan.
  11. *
  12. * Developer Technical Support Apple II Sample Code
  13. *
  14. * The purpose of this code is to handle dialogs in a variety of ways
  15. * that are more robust than what the toolbox offers.  It also supports
  16. * the new movable/modeless dialog types described in the latest human
  17. * interface guidelines.
  18. *
  19. *******************************************************************************
  20. *
  21. * Here is some C sample code that uses fakeModalDialog.  This code is
  22. * for an about box.  What is different about this about box is that
  23. * you can use menus while the about box is on the screen.  This means
  24. * that you can use desk accessories while the about box is active.
  25. * It also means that you can quit the application at this time.
  26. * You can also close the about box with the close menu option.
  27. *
  28. * This sample uses the modal mode with menus for the about box.  Since
  29. * menus are available, there is more support (code) necessary from the
  30. * application.  The application has to detect that the user chose
  31. * close from the menu and take appropriate action, for example.
  32. *
  33. * First, a little about fakeModalDialog:
  34. *
  35. * fakeModalDialog returns a long as a result.
  36. * If the result is NULL:
  37. *     Nothing happened.  Unlike ModalDialog, control is returned to
  38. *     the application during null events.  This is so the application
  39. *     can do stuff like switch cursors, or other idle tasks.
  40. * If bit 31 of the result is true:
  41. *     The user chose a menu item.  Bits 0-15 are the menu item ID.
  42. *                                  Bits 16-30 are the menu ID.
  43. * If bit 31 of the result is false:
  44. *     The user clicked on a control.  Bits 0-30 are the control ID.
  45.  
  46. * Now, the sample code fragment:
  47.  
  48. *   #define aboutBoxID 0x1001L
  49. *
  50. *   void    doAboutBox()
  51. *   {
  52. *       WindowPtr       wptr, keepPort;
  53. *       unsigned long   id;
  54. *       unsigned int    item;
  55. *       keepPort = GetPort();   /* Preserve the current port. */
  56. *
  57. *       wptr = NewWindow2(NULL, NULL, NULL, NULL, 2, aboutBoxID, rWindParam1);
  58. *           /* Open the about box from a resource. */
  59. *
  60. *       if (!_toolErr) {            /* If the window opened successfully... */
  61. *           aboutWindow = wptr;     /* Set the aboutWindow global variable. */
  62. *                                   /* This tells other routines what state */
  63. *                                   /* we are in.                           */
  64. *
  65. *           for (;;) {      /* Loop, due to NULL events being returned. */
  66. *
  67. *               id = fakeModalDialog(
  68. *                   &event,         /* Pointer to extended event record.   */
  69. *                   NULL,           /* Use default update procedure.       */
  70. *                   NULL,           /* There will be no event mods.        */
  71. *                   NULL,           /* Do standard beep.                   */
  72. *                   fmdMenuSelect+  /* Allow pullDowns.                    */
  73. *                   fmdMenuKey+     /* Allow menu keys.                    */
  74. *                   fmdDeskAcc+     /* Allow desk accessories.             */
  75. *                   fmdUpdateAll    /* Update all windows, not just about. */
  76. *               );
  77. *
  78. *               item = id;          /* Get lo-word from result. */
  79. *
  80. *               if (id & 0x80000000L) {             /* If menu command...    */
  81. *                   if (item == 255) {              /* If close command then */
  82. *                       HiliteMenu(0, FileMenuID);  /* turn menu inv. off.   */
  83. *                       break;                      /* Go close about box.   */
  84. *                   }
  85. *                   doMenuCommand(id);      /* Do other menus (like quit).   */
  86. *                   if (quitFlag) break;    /* User did do a quit from menu. */
  87. *               }
  88. *               else {                          /* ...else handle controls. */
  89. *                   if (item == 1) break;       /* User clicked OK button.  */
  90. *               }
  91. *           }
  92. *
  93. *           SetPort(keepPort);      /* Put port back before closing about. */
  94. *           CloseWindow(wptr);      /* Close aboutBox.                     */
  95. *           aboutWindow = NULL;     /* Let others know it is closed.       */
  96. *           appSetMenus();          /* Update the menus to reflect a new.  */
  97. *       }                           /* top window.                         */
  98. *   }
  99.  
  100. * An interesting point here is the call to appSetMenus.  This is a routine
  101. * in the application that is responsible for putting the menus in the
  102. * correct state.  fakeModalDialog automatically calls this routine (if told
  103. * to) whenever an activate event occurs that it gets a chance to see.
  104. * fakeModalDialog may not see the activate event  only if a desk accessory
  105. * is open, just behind the about box.  When the about box is closed, the
  106. * desk accessory gets the activate event.  fakeModalDialog never got an
  107. * activate event, so it didn't know to call the menu update routine.  This
  108. * situation can only occur when a desk accessory is just behind the window
  109. * to be closed.  As a safe rule, whenever a window is closed, the menu
  110. * update routine should be called by the application.  (Something like this
  111. * should be done anyway.)
  112.  
  113. * To tell fakeModalDialog to automatically call a menu update routine when
  114. * it gets an activate event, make a call to fmdSetMenuProc.  For an application
  115. * menu update routine called appSetMenus, you would tell fakeModalDialog
  116. * about it by the following:
  117. *     fmdSetMenuProc(appSetMenus);
  118. * To turn off menu updating again, do this:
  119. *     fmdSetMenuProc(NULL);
  120.  
  121. * fmdEditMenu figures the state of cut, copy, paste, and clear in
  122. * the edit menu based on the state of controls in the window.
  123. * It looks up the target control (either lineEdit or textEdit) and
  124. * then sets the states appropriately.  For lineEdit, if anything
  125. * is selected, then cut, copy and clear are available.  If there is
  126. * anything in the scrap, then paste is also available.  TextEdit 
  127. * works the same way, unless the textEdit control is a read-only
  128. * control.  In that case, cut, paste, and clear are not available.
  129. * If there is no lineEdit or textEdit control, then the state of
  130. * these menu items is left alone.  The application needs to take care
  131. * of them in that case.  (It is possible that there are custom
  132. * controls for the application that can use these menu items, and
  133. * there is no way for fakeModalDialog to know about them.  Therefore
  134. * the correct thing to do is to do nothing.)
  135.  
  136. * fmdFindCursorCtl is used to find which control is at a certain point.
  137. * The toolbox call FindControl can't be used for this because textEdit
  138. * controls become active when called with a point in them.  That is not
  139. * the desired effect of fmdFindCursorCtl.  If you just want to know what
  140. * control you are over and have nothing affected, then use this entry
  141. * point.  It is used by fakeModalDialog to determine whether or not to
  142. * display an i-beam cursor.  If the i-beam bit is set and the user moves
  143. * the mouse over a lineEdit or textEdit control, then the cursor changes
  144. * to an i-beam.  Note that the scrollbars for a textEdit control are
  145. * considered a separate control.  This is so that the cursor stays
  146. * an arrow when over the scrollbars.
  147.  
  148. * Back to fakeModalDialog:
  149.  
  150. * Some sample calls (in C) would look like:
  151. *   ctlID = fakeModalDialog(&event, NULL, NULL, NULL, 0);
  152. *   ctlID = fakeModalDialog(&event, updateProc, NULL, -1L, 0);
  153. *   ctlID = fakeModalDialog(&event, updateProc, eventHook, beepProc, flags);
  154. *
  155. * The parameters are:
  156. *
  157. * event:          A pointer to an extended (for 5.0) event record.
  158. * updateProc:     Pointer to function to update the window.  Pass a NULL for
  159. *                 default.  (The default entry point is called fmdStdDrawProc.)
  160. * eventHook:      Pointer to function that is called after the GetNextEvent
  161. *                 call and before any processing occurs on that event.  This
  162. *                 is more useful than a filter.  You can simply change the
  163. *                 event by changing the event record.  For example:  Let's say
  164. *                 that you want to be able to cancel a modal dialog by pressing
  165. *                 either openApple-period or ESC.  The problem is that,
  166. *                 although you can have two key equivalents for a
  167. *                 super-control, theway that modifiers are determined is the
  168. *                 same for both keys.  This means that you can't have
  169. *                 openApple-period and ESC asyour two key equivalents.  With
  170. *                 this event hook, you can lookat the event, and if it is the
  171. *                 openApple-period, you can simply change the event record so
  172. *                 that it is an ESC with no openApple modifier.  Then when you
  173. *                 return to fakeModalDialog, it will handle the event as if the
  174. *                 user simply typed an ESC.  By using this technique, you can
  175. *                 have as many modifiers as you want.  If you wish to filter
  176. *                 out an event, you would simply changethe event type to a
  177. *                 NULL event.
  178. * beepProc:       Pointer to custom beep function.  fakeModalDialog calls this
  179. *                 if there is any mouseDown outside the window, just like
  180. *                 ModalDialog.If you wish it to beep like ModalDialog, pass a
  181. *                 NULL.  If you wish it to do nothing, pass a -1.
  182. *                 If you wish a custom beep function, pass it a pointer to
  183. *                 that function.
  184. * flags, bit 0:   Cut/Copy/Paste for lineEdit items would normally involve
  185. *                 the scrap.  When this bit is true, the scrap is not involved
  186. *                 when using lineEdit items.  This may be useful to protect a
  187. *                 large scrap for an application from being hit with something
  188. *                 trivial.
  189. *        bit 1:   If true, allow menu pullDowns for movable/modal dialogs.
  190. *                 If they are allowed, then the return value is the menu
  191. *                 item ID (low-word) and the menu ID (hi-word).  To
  192. *                 distinguish from ctlID's, thehi-bit (bit 31) is set.  This
  193. *                 means that if you are allowing menu selections, you can't have
  194. *                 any menu ID's with a hi-bit-on ID.  It also means that you
  195. *                 can't have controls with bit 31 on either.
  196. *        bit 2:   If true, allow menu keys.  Return values work the same as for
  197. *                 pullDowns.
  198. *        bit 3:   If true, use i-beam cursor for lineEdit & textEdit ctls.
  199. *                 Otherwise, use an arrow cursor everywhere.
  200. *        bit 4:   If true, automatically handle desk accessories.  This means
  201. *                 that bit 1 must be true to have fakeModalDialog open the DA.
  202. *                 If the DA is already open, the user can click on it, and it
  203. *                 will become active, even if bit 1 is false.
  204. *        bit 14:  If true, update all windows.  The toolbox call ModalDialog
  205. *                 does not update other windows.  This takes away a lot of the
  206. *                 point of movable/modal dialogs.  The whole point is so that
  207. *                 you can see what is behind it.  When you move the dialog, if
  208. *                 the windows in back didn't update, then there would be no
  209. *                 point in moving the window.  If you want, you can set this
  210. *                 bit false, and it will update only the front-most
  211. *                 application window.
  212. *        bit 15:  This is the bit that determines whether or not a dialog is
  213. *                 movable.  If it is true, then the dialog is movable.  To be
  214. *                 moved, however, it has to have a title bar (the drag region)
  215. *                 and it has to have the fMove bit set.  Without these also,
  216. *                 the window still won't be able to be moved.
  217. *                 
  218. * ctlID:          Control that was hit, or menu that was chosen.
  219. *                 bit 31 off, it is a control ID.
  220. *                 bit 31 on, it is a menu ID (hi-word), menu item ID (lo-word).
  221. *
  222. * There is one more thing to worry about, and that is the border of the window.
  223. * The window manager doesn't allow you have an alert frame and a title at the
  224. * same time.  If you set both of these bits in the wFrameBits field, then the
  225. * alert border is drawn wrong.  It would be ideal for fakeModalDialog if this
  226. * restriction didn't exist.  Then the window attributes all could be chosen via
  227. * the window frame bits in a resource.  Unfortunately, this isn't the case.  To
  228. * manage this restriction, the default update procedure, under certain
  229. * conditions, draws the alert frame itself.  If fAlert is set, then the alert
  230. * border isn't drawn by the default update procedure.  The update procedure
  231. * doesn't have to draw it, since it is automatically drawn by the window
  232. * manager.  If fAlert is set, then the dialog doesn't have a title bar, due to
  233. * the window manager restriction.  If fAlert isn't set, then the default update
  234. * procedure draws the alert border.  The alert border is drawn as part of the
  235. * content of the window.  Due to this, the coordinates you use for the content
  236. * of the window have to be a little different, to make space for the border.
  237. * The upper-left-hand corner of the window is really 10,4, (4,4 for 320 mode)
  238. * instead of 0,0.  So far, we have discussed how the alert border gets drawn,
  239. * either by the window manager, or by the default update procedure for
  240. * fakeModalDialog.  It is possible that you don't want an alert border at all.
  241. * If you don't, then fAlert should be off, and you should turn on fFlex.  fFlex
  242. * was used because it should be able to be set from a resource, and all other
  243. * bits would have an adverse effect.  Dialogs don't have grow boxes and zoom
  244. * boxes, so fFlex is meaningless for dialogs (until now).
  245.